Tween QT Atom Container24

QuickTime 4 Reference

General Tween Atoms

kTweenEntry

Specifies a tween, which can be either a single tween, a tween in a tween sequence, or an interpolation tween.

Its parent is the tween QT atom container (which you specify with the constant kParentAtomIsContainer ).

The index of a kTweenEntry atom specifies when it was added to the QT atom container ; the first added has the index 1 , the second 2 , and so on. The ID of a kTweenEntry atom can be any ID that is unique among the kTweenEntry atoms contained in the same QuickTime atom container.

This atom is a parent atom. It must contain the following child atoms:

A kTweenType atom that specifies the tween type.
One or more kTweenData atoms that contain the data for the tween. Each kTweenData atom can contain different data to be processed by the tween component, and a tween component can process data from only one kTweenData atom a time. For example, an application can use a list tween to animate sprites. The kTweenEntry atom for the tween could contain three sets of animation data, one for moving the sprite from left to right, one for moving the sprite from right to left, and one for moving the sprite from top to bottom. In this case, the kTweenEntry atom for the tween would contain three kTweenData atoms, one for each data set. The application specifies the desired data set by specifying the ID of the kTweenData atom to use.

A kTweenEntry atom can contain any of the following optional child atoms:

A kTweenStartOffset atom that specifies a time interval, beginning at the start of the tween media sample, after which the tween operation begins. If this atom is not included, the tween operation begins at the start of the tween media sample.
A kTweenDuration atom that specifies the duration of the tween operation. If this atom is not included, the duration of the tween operation is the duration of the media sample that contains it.

If this atom specifies a path tween, it can contain the following optional child atom:

A kTweenFlags atom containing flags that control the tween operation. If this atom is not included, no flags are set.

If a kTweenEntry atom specifies an interpolation tween, it must contain the following child atom(s):

A kTweenInterpolationID atom for each kTweenData atom to be interpolated. The ID of each kTweenInterpolationID atom must match the ID of the kTweenData atom to be interpolated. The data for a kTweenInterpolationID atom specifies a kTweenEntry atom that contains the interpolation tween to use for the kTweenData atom.

If this atom specifies an interpolation tween, it can contain either of the following optional child atoms:

A kTweenOutputMin atom that specifies the minimum output value of the interpolation tween. The value of this atom is used only if there is also a kTweenOutputMax atom with the same parent. If this atom is not included and there is a kTweenOutputMax atom with the same parent, the tween component uses 0 as the minimum value when scaling output values of the interpolation tween.
A kTweenOutputMax atom that specifies the maxiumum output value of the interpolation tween. If this atom is not included, the tween component does not scale the output values of the interpolation tween.

kTweenStartOffset

For a tween in a tween track of a QuickTime movie, specifies a time offset from the start of the tween media sample to the start of the tween. The time units are the units used for the tween track.

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only one kTweenStartOffset atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is TimeValue .

This atom is optional. If it is not included, the tween operation begins at the start of the tween media sample.

kTweenDuration

Specifies the duration of a tween operation. When a QuickTime movie includes a tween track, the time units for the duration are those of the tween track. If a tween component is used outside of a movie, the application using the tween data determines how the duration value and values returned by the component are interpreted.

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only one kTweenDuration atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is TimeValue .

This atom is optional. If it is not included, the duration of the tween is the duration of the media sample that contains it.

kTweenData

Contains data for a tween.

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain any number of kTweenData atoms. Each kTweenData atom can contain different data to be processed by the tween component, and a tween component can process data from only one kTweenData atom a time. For example, an application can use a list tween to animate sprites. The kTweenEntry atom for the tween could contain three sets of animation data, one for moving the sprite from left to right, one for moving the sprite from right to left, and one for moving the sprite from top to bottom. In this case, the kTweenEntry atom for the tween would contain three kTweenData atoms, one for each data set. The application would specify the desired data set by specifying the ID of the kTweenData atom to use.

The index of a kTweenData atom specifies when it was added to the kTweenEntry atom; the first added has the index 1 , the second 2 , and so on. The ID of a kTweenData atom can be any ID that is unique among the kTweenData atoms contained in the same kTweenEntry atom.

At least one kTweenData atom is required in a kTweenEntry atom.

For single tweens, a kTweenData atom is a leaf atom. It can contain data of any type.

For polygon tweens, a kTweenData atom is a leaf atom. The data type of its data is Fixed[27] , which specifies three polygons as described in "Using Path Tween Components" .

For path tweens, a kTweenData atom is a leaf atom. The data type of its data is Handle , which contains a QuickTime vector as described in "Using Path Tween Components" .

In interpolation tweens, a kTweenData atom is a leaf atom. It can contain data of any type. An interpolation tween can be any tween other than a list tween that returns a time value, as described in "Interpolation Tweens" .

In list tweens, a kTweenData atom is a parent atom that must contain the following child atoms:

A kListElementType atom that specifies the atom type of the elements iof the tween.
One or more leaf atoms of the type specified by the kListElementType atom. The data for each atom is the result of a list tween operation, as described in "Using a List Tween Component".

kNameAtom

Specifies the name of a tween. The name, which is optional, is not used by tween components, but it can be used by applications or other software.

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only one kNameAtom atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. Its data type is StringPtr .

This atom is optional. If it is not included, the tween does not have name.

kTweenType

Specifies the tween type (the data type of the data for the tween operation).

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only one kTweenType atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is OSType .

This atom is required.

Path Tween Atoms

kTweenFlags

Contains flags that control the tween operation. One flag that controls path tweens is defined:

The kTweenReturnDelta flag applies only to path tweens (tweens of type kTweenTypePathToFixedPoint, kTweenTypePathToMatrixTranslation, kTweenTypePathToMatrixTranslationAndRotation, kTweenTypePathXtoY, or kTweenTypePathYtoX). If the flag is set, the tween component returns the change in value from the last time it was invoked. If the flag is not set, or if the tween component has not previously been invoked, the tween component returns the normal result for the tween.

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only one kTweenFlags atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is Long .

This atom is optional. If it is not included, no flags are set.

kInitialRotationAtom

Specifies an initial angle of rotation for a path tween of type kTweenTypePathToMatrixRotation , kTweenTypePathToMatrixTranslation , or kTweenTypePathToMatrixTranslationAndRotation .

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only one kInitialRotationAtom atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. Its data type is Fixed .

This atom is optional. If it is not included, no initial rotation of the tween is performed.

List Tween Atoms

kListElementType

Specifies the atom type of the elements in a list tween.

Its parent atom is a kTweenData atom.

A kTweenEntry atom can contain only one kListElementType atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. Its data type is QTAtomType .

This atom is required in the kTweenData atom for a list tween.

3D Tween Atoms

kTween3dInitialCondition

Specifies an initial transform for a 3D tween whose tween type is one of the following: kTweenType3dCameraData, kTweenType3dMatrix, kTweenType3dQuaternion, kTweenType3dRotate, kTweenType3dRotateAboutAxis, kTweenType3dRotateAboutAxis, kTweenType3dRotateAboutPoint, kTweenType3dRotateAboutVector, kTweenType3dScale, or kTweenType3dTranslate.

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only one kTween3dInitialCondition atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is as follows:

For a kTweenType3dCameraData tween, its data type is TQ3CameraData.
For a kTweenType3dMatrix tween, its data type is TQ3Matrix4x4 .
For a kTweenType3dQuaternion tween, its data type is TQ3Quaternion .
For a kTweenType3dRotate tween, its data type is TQ3RotateTransformData .
For a kTweenType3dRotateAboutAxis tween, its data type is TQ3RotateAboutAxisTransformData .
For a kTweenType3dRotateAboutPoint tween, its data type is TQ3RotateAboutPointTransformData .
For a kTweenType3dRotateAboutVector tween, its data type is TQ3PlaneEquation .
For a kTweenType3dScale tween, its data type is TQ3Vector3D .
For a kTweenType3dTranslate tween, its data type is TQ3Vector3D .

This atom is optional. For each tween type, the default value is the data structure that specifies an identity transform, that is, a transform that does not alter the 3D data.

Interpolation Tween Atoms

kTweenOutputMax

Specifies the maximum output value of an interpolation tween. If a kTweenOutputMax atom is included for an interpolation tween, output values for the tween are scaled to be within the minimum and maximum values. The minimum value is either the value of the kTweenOutputMin atom or, if there is no kTweenOutputMin atom, 0 . For example, if an interpolation tween has values between 0 and 4, and it has kTweenOutputMin and kTweenOutputMax atoms with values 1 and 2, respectively, a value of 0 (the minimum value before scaling) is scaled to 1 (the minimum specified by the kTweenOutputMin atom), a value of 4 (the maximum value before scaling) is scaled to 2 (the maximum specified by the kTweenOutputMax atom), and a value of 3 (three-quarters of the way between the maximum and minimum values before scaling) is scaled to 1.75 (three-quarters of the way between the values of the kTweenOutputMin and kTweenOutputMax atoms).

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only on e kTweenOutputMax atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is Fixed .

This atom is optional. If it is not included, QuickTime does not scale interpolation tween values.

kTweenOutputMin

Specifies the minimum output value of an interpolation tween. If both kTweenOutputMin and kTweenOutputMax atoms are included for an interpolation tween, output values for the tween are scaled to be within the minimum and maximum values. For example, if an interpolation tween has values between 0 and 4, and it has kTweenOutputMin and kTweenOutputMax atoms with values 1 and 2, respectively, a value of 0 (the minimum value before scaling) is scaled to 1 (the minimum specified by the kTweenOutputMin atom), a value of 4 (the maximum value before scaling) is scaled to 2 (the maximum specified by the kTweenOutputMax atom), and a value of 3 (three-quarters of the way between the maximum and minimum values before scaling) is scaled to 1.75 (three-quarters of the way between the values of the kTweenOutputMin and kTweenOutputMax atoms).

If a kTweenOutputMin atom is included but a kTweenOutputMax atom is not, QuickTime does not scale interpolation tween values.

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only on e kTweenOutputMin atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is Fixed .

This atom is optional. If it is not included but a kTweenOutputMax atom is, the tween component uses 0 as the minimum value for scaling values of an interpolation tween.

kTweenInterpolationID

Specifies an interpolation tween to use for a specified kTweenData atom. There can be any number of kTweenInterpolationID atoms for a tween, one for each kTweenData atom to be interpolated.

Its parent atom is a kTweenEntry atom.

The index of a kTweenInterpolationID atom specifies when it was added to the kTweenEntry atom; the first added has the index 1 , the second 2 , and so on. The ID of a kTweenInterpolationID atom must (1) match the atom ID of the kTweenData atom to be interpolated, and (2) be unique among the kTweenInterpolationID atoms contained in the same kTweenEntry atom.

This atom is a leaf atom. The data type of its data is QTAtomID .

This atom is required for an interpolation tween.

Region Tween Atoms

kTweenPictureData

Contains the data for a QuickDraw picture. Used only by a kTweenTypeQDRegion tween, as described in "Tween Components for QuickDraw 3D" .

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only on e kTweenPictureData or kTweenRegionData atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is Picture .

Either a kTweenPictureData or kTweenRegionData atom is required for a kTweenTypeQDRegion tween.

kTweenRegionData

Contains the data for a QuickDraw region. Used only by a kTweenTypeQDRegion tween, as described in "Tween Components for QuickDraw 3D" .

Its parent atom is a kTweenEntry atom.

A kTweenEntry atom can contain only on e kTweenRegionData or kTweenPictureData atom. The ID of this atom is always 1 . The index of this atom is always 1 .

This atom is a leaf atom. The data type of its data is Region .

Either a kTweenPictureData or kTweenRegionData atom is required for a kTweenTypeQDRegion tween.

Sequence Tween Atoms

kTweenSequenceElement

Specifies an entry in a tween sequence.

Its parent is the tween QT atom container (which you specify with the constant kParentAtomIsContainer ).

The ID of a kTweenSequenceElement atom must be unique among the kTweenSequenceElement atoms in the same QT atom container. The index of a kTweenSequenceElement atom specifies its order in the sequence; the first entry in the sequence has the index 1 , the second 2 , and so on.

This atom is a leaf atom. The data type of its data is TweenSequenceEntryRecord , a data structure that contains the following fields:

endPercent , a value of type Fixed that specifies the point in the duration of the tween media sample at which the sequence entry ends. This is expressed as a percentage; for example, if the value is 75.0, the sequence entry ends after three-quarters of the total duration of the tween media sample have elapsed. The sequence entry begins after the end of the previous sequence entry or, for the first entry in the sequence, at the beginning of the tween media sample.
tweenAtomID , a value of type QTAtomID that specifies the kTweenEntry atom containing the tween for the sequence element. The kTweenEntry atom and the kTweenSequenceElement atom must both be a child atoms of the same tween QT atom container.
dataAtomID , a value of type QTAtomID that specifies the kTweenData atom containing the data for the tween. This atom must be a child atom of the atom specified by the tweenAtomID field.